============================================================== Copyright 1994 Northeast Data Corp. All Rights Reserved ============================================================== ============================================================== IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT Before experimenting with the Netcom control, read the information below. The Netcom control allows you to perform network operations that disrupt network communication with your PC. Resetting the network adapter or deleting names from the NetBIOS name table indiscriminantly will destroy communication between your PC and other workstations on the network. ============================================================== Netcom VBX V1.5 The Netcom VBX control implements NetBIOS general, session, and datagram support. All common NetBIOS functions are supported. The control conforms to Visual Basic release 1.0, so it is compatible with Visual Basic versions 1.0, 2.0, 3.0 and higher, and with Visual C++ versions 1.0, 1.5 and higher. The only difference between the demo version of the control and the commercial version is that the demo version displays a dialog box that allows the user to register the control with Northeast Data. There are no other functional differences. Here are the overall capabilities: - Support for all standard NetBIOS emulations. This includes NetBIOS services running on LAN Manager, LAN Server, Novell, Banyan VINES, 3COM. - Support for multiple network adapters. - Multiple Netcom controls within the same application. - Interprocess communication between applications on the same workstation. - Communication between applications running on separate workstations. - Adapter status and reset. - NetBIOS name support. - NetBIOS session support. - NetBIOS datagram support. =================== The demo version =================== (Does not apply if you have purchased a licensed version) The demo version of the control will allow you to perform all functions implemented by the commercial version. The only difference is that a registration dialog box is displayed when the control is first loaded. By registering the control with Northeast Data Corp., you get: - The commercial version of the control - A telephone and FAX number for support - A Compuserve ID for support - Free maintenance release updates - A discount on major releases - More information about using NetBIOS =================== System Requirements =================== You must have a NetBIOS application service running on your PC. This requires a network adapter (etnernet, token ring, arcnet, etc.). This service must be compatible with Microsoft Windows. Microsoft Windows version 3.0 or 3.1. =================== Installation =================== Copy the NETCOM.VBX file to your Windows or Windows\System directory. Before starting Windows, make sure you have loaded any network services that are required for NetBIOS support. Start Windows and run Visual Basic or the PROJECT1.EXE program supplied with the Netcom control. If you are running Visual Basic, you can load the PROJECT1.MAK file or load the Netcom control into your own project by using the "Add File" item under the FILE menu in Visual Basic. =================== Control Properties =================== Note: In the descriptions below, there are references to the "remote" workstation. If you are doing interprocess communication on your PC, "remote" refers to the other application on your PC. If you are communicating with a real remote workstation, "remote" refers to that workstation. Since the Netcom control is re-entrant, you can actually perform inter-process communication within the control itself. In other words, you can send data to "yourself". It is perfectly OK to have the Netcom control send data to and from itself or between Netcom controls in the same application. This has no value within the same application, other than allowing you to experiment with the control. Adapter The network adapter number. If you have only one network adapter, this number is always 0. You change this value to choose a different adapter. Command All of the following commands are executed on the adapter specified in the "Adapter" property, which defaults to zero and is the correct value if you only have one network adapter. For all commands, you should set up an error handler (using the On Error VB statement). The error codes returned are documented in the NETCOM.H file (the errors with the "VBERR_" prefix. 1 - Initialize Sets up the control for use by your application. This command must be executed before you perform any other commands and before any properties that perform network operations are executed. 2 - RegisterName Registers the name specified in the "NetName" property with NetBIOS. The name is registered as a unique network name. The command fails if the name is already registered by anyone on the network. 3 - RegisterGroup Registers the name specified in the "NetName" property with NetBIOS. The name is registered as a group name. The command fails if the name is already registered on your workstation, or if another workstation has registered the name as a unique name (see command #2). Group names can be used to send data to multiple workstations. 4 - SendDatagram Sends the data specified in the "SendData" property to the name specified in the "RemoteName" property. The RemoteName property can be set to a unique name or a group name. The datagram is sent with the sender name specified in the "NetName" property. This name must be registered (using command 2 or 3) before sending the datagram. All workstations that have registered the remote name and have posted a "Receive Datagram" will receive the data you specify in the SendData property. Since this is a datagram, you receive no notification that other workstations have received the data. 5 - ReceiveDatagram Sets up a "receive datagram" for the name specified in the "NetName" property. You have to register NetName as a unique name or a group name before executing this command. After executing this command, control will be returned to your application. When a datagram is received, the Netcom "RecDatagram" procedure will be called (see below, under "Events"). 6 - Call An attempt is made to establish a session with the workstation that has registered the name specified in the "RemoteName" property. The name of the caller (you) is specified in the "NetName" property. You have to register the NetName before executing this command. You do not have to register the RemoteName. Both names can be either unique or group names. Control is returned immediately to your application. When a connection is established with a remote workstation, the "NewSendSession" routine is called in the Netcom control. 7 - Listen A listen is set up for the name specified in the "RemoteName" property. The remote workstation expects you to supply a valid name in the "NetName" property. The NetName must be a unique or group name that you have registered using commands 2 or 3. This command returns immediately to your application. When a remote workstation calls you, the "NewRecSession" routine in the NetCom control is called. You can use this event to start sending or receiving data to or from the remote workstation. 8 - Send Data you have specified in the "SendData" property is sent to the remote workstation. Control is immediately returned to your application. When the remote workstation has received the data, the "SendComplete" routine in the Netcom control is executed. You can use this notification to determine when to send the next block of data. The data is sent to the session specified in the "SendSession" property. 9 - Receive A wait for data is set up for the session specified in the "RecSession" property. Control is immediately returned to your application. When data is received, the "RecData" routine in the Netcom control is called. In order to receive more data from the sender, you must issue another "Receive" command. This should be done immediately to prevent the sender from timing out. 10 - HangupReceive Terminates the session specified in the "RecSession" property. The remote workstation is notified. You can no longer receive data on this session. 11 - HangupSend Terminates the session specified in the "SendSession" property. The receiving workstation, if any, is notified. You can no longer send data on this session. 12 - CancelAll Cancels all network requests. This includes all commands for sending or receiving datagrams or data. It does not clear any registered names from the name table. 13 - ResetAdapter Cancels all network requests and clears all names from the name table. USE THIS COMMAND WITH CAUTION. If you are running on a network, this command will delete all names that other workstations may be using to communicate with your workstation. The adapter will be set to the same state is was when your workstation was initially booted (before any network applications were started). 14 - DeleteName Deletes the name specified in the "NetName" property from the NetBIOS name table. USE THIS COMMAND WITH CAUTION. Network servers and applications register network names for communication with your workstation. If you delete names that have been registered by your network applications, these applications will no longer be able to perform network operations. This command deletes a group name or unique name, depending on the name specified in the NetName property. 15 - ReceiveAny Sets up a receive for any remote workstation attempting to send data to the name you specify in the "NetName" property. This is different from the "Receive" command, which only accepts data from a workstation that has registered the name you specify in the "RemoteName" property. Control is returned immediately to your application. When a remote workstation sends data, the "RecData" routine in the Netcom control is called. If you specify 255 in the "NameNumber" property, instead of setting the "NetName" property, a "Receive-any-for-any" command is executed. This will set up a receive for any remote workstation sending data to any name (rather than a single name) on your workstation. 16 - AdapterStatus Displays a dialog box containing information about the adapter you specify in the "RemoteName" property. If you specify "*" in this property, information from your own adapter will be displayed. If you specify a unique or group name, information from the first adapter that has registered the specified name will be displayed. 17 - ListNames The "NetName" routine in the Netcom control is called for every name in the NetBIOS name table for the adapter specified in the "RemoteName" property. If the RemoteName property is "*", you will get all the names registered on your workstation. If the remotename is set to a unique or group name, you will get the list of names registered by the first adapter on the network that has registered the specified name. 18 - RecSessionStat Gets the session status for the session specified in the "RecSession" property. This command is not very useful, since the only status ever available is either 0 (failure) or 3 (session established). The other statuses only occur in rare situations. The "SessionStatus" property is set to the status of the receive session. Session status values are: 1 - Listen pending 2 - Call pending 3 - Session established 4 - Hang Up pending 5 - Hang Up complete 6 - Session aborted Note: In order to get the session information, the name specified in the NetName property must be the name that was used when the session was established. Specify "*" in the NetName to get the status of the session regardless of the name that originally registered the session. 19 - SendSessionStat Gets the session status for the session specified in the "SendSession" property. This command is not very useful, since the only status ever available is either 0 (failure) or 3 (session established). The other statuses only occur in rare situations. The "SessionStatus" property is set to the status of the send session. Session status values are: 1 - Listen pending 2 - Call pending 3 - Session established 4 - Hang Up pending 5 - Hang Up complete 6 - Session aborted Note: In order to get the session information, the name specified in the NetName property must be the name that was used when the session was established. Specify "*" in the NetName to get the status of the session regardless of the name that originally registered the session. 20 - ReceiveBroadcast Sets up a "Receive Datagram" for any workstation sending a broadcast datagram. Control returns immediately to your application. When a datagram is broadcasted by a remote workstation, the RecDatagram routine is called in the Netcom control. 21 - SendBroadcast Sends a datagram to all workstations on the network. You specify the data to send in the "SendData" property. All workstations that have posted a "Receive Broadcast Datagram" will receive the message. Since this is a datagram, your workstation will not be notified as to whether or not any workstations have received the message. 22 - ReceiveAnyForAny Posts a receive for any sender attempting to send data to any session you have established. DragIcon A standard Visual Basic property. DragMode A standard Visual Basic property. Index A standard Visual Basic property. Left A standard Visual Basic property. Name A standard Visual Basic property. NameNumber The name number of the NetBIOS name specified in the "NetName" property. You can override this value for sending broadcast datagrams. This property is set automatically whenever you change the NetName property. NetName The NetBIOS name for performing various network requests. This can be a unique name or group name. You set this property and then issue a "registerName" or "registerGroup" command to put the name into the NetBIOS name table. PermanentName Your adapter permanent node name. This is filled in automatically when you issue the "Initialize" command. RecSession The number of the network session returned from a "NetListen" command. RecTimeout The number of half-seconds that will be waited on a session RECEIVE transaction. This value is only used when a CALL or LISTEN command is issued. It establishes the RECEIVE timeout period for all receive transactions on the established session. You cannot change the timeout value on a session after it has been established. RemoteName The NetBIOS remote name used for performing CALL, RECEIVE, and SEND commands. SendData Data to be sent as a datagram or to be sent to a remote workstation using the "SendDatagram", "SendBroadcast", or "Send" commands. SendSession The number of the network session returned from the "NetCall" command. SendTimeout The number of half-seconds that will be waited on a session SEND transaction. This value is only used when a CALL or LISTEN command is issued. It establishes the SEND timeout period for all send transactions on the established session. You cannot change the timeout value on a session after it has been established. SessionStatus The status from the "SendSessionStat" or "RecSessionStat" commands. The values are: 0 - Unknown 1 - Listen Pending 2 - Call Pending 3 - Session Established 4 - Hangup Pending 5 - Hangup Complete 6 - Session Aborted TabIndex A standard Visual Basic property. TabStop A standard Visual Basic property. Tag A standard Visual Basic property. Top A standard Visual Basic property. Trace If set to TRUE, diagnostic messages are displayed for every network command performed. This is useful for troubleshooting your application. Visible A standard Visual Basic property. ============ Events ============ RecDatagram (Datagram as String,Sender as String) Called when a datagram is received. "Datagram" is the string that was sent by the remote workstation. "Sender" is the name that the remote workstation used as the sender of the datagram. NewSendSession (Receiver as String,I as Integer) Called when a new session has been established as a result of issuing the "Call" command. "Receiver" is the name that the responding workstation used to connect with your workstation. "I" is the session number. NewRecSession (Sender as String,I as Integer) Called when a new session has been established as a result of issuing the "Listen" command. "Sender" is the name that the remote (sending) workstation used to connect with your workstation. "I" is the session number. NetName (S as String,I as Integer) Called repeatedly when a "ListNames" command is issued, for each name found in the NetBIOS name table. S is the registered name. I is the name number. RecData (RecData as String,I as Integer) Called when data is received on a session. RecData is the data that was received. I is the session number, which matches the session number that was returned from the "Listen" command. SessionClosed (I as Integer) Called when a session has been closed by the remote workstation. I is the number of the session. You can no longer issue sends or receives on this session. SessionInfo Called for each session found when the the RecSessionStat or SendSessionStat commands are specified. All sessions established by the name specified in the NetName property are returned. To get a list of all sessions regardless of the local name, specify "*" in the NetName property. The local remote name, local name, session state, and session number are returned in the event arguments. SendComplete (I as Integer) A remote workstation has successfully recieved the data you sent in a "Send" command. I is the session number. ============================= General Notes ============================= The demo application uses most of the NetBIOS functions implemented in the Netcom control. The TRACE property is set to TRUE in the demo, so you will see many messages as commands are executed. Since many operations are asynchronous, you will see messages that appear to be out of order. For example, you may see a message indicating that a datagram has been received - followed by a message indicating that the datagram has been sent. This is normal behavior. With the TRACE function in operation, you will see messages indicating that operations are successful - possibly followed by messages indicating that an operation has failed. This is because many NetBIOS commands are performed in two steps - the first step being the submission of a request to the NetBIOS driver. The driver acknowledges that it has received the request (hence the "success" message). After the operation has been completed, NetBIOS notifies the Netcom control as to the final status of the operation. This status may be "success" or "failure" and is reported back to the application (and directly to the screen if the TRACE function is active). Certain NetBIOS operations do not happen instantly. A request to add a new name to the name table is time consuming (perhaps 5 seconds or more). This request is handled synchronously by the Netcom control. It does not return control to your application until the name has been added or the attempt fails. The Netcom control has been designed with consideration efficient operation of your workstation and ease of programming. There are "tradeoffs" between asynchronous vs. synchronous operations. Synchronous operations are easier for your application to deal with, but require suspending all execution in your application until the operation completes. Asynchronous operations allow your application to do other work while a request is being processed, but are more difficult for your application to work with - you have to handle the events that are sent to the Netcom control. It is possible to do both sends and receives on the same session, even though you initiated the session via a Call or Listen. Completion of a "Call" fills in the "Sendsession" property. Completion of a "Listen" fills in the "RecSession" property. If you perform a "Listen" and then want to do a "Send", copy the "RecSession" value into the "SendSession" property and then issue the "Send" command. Do the reverse for performing a "Receive" on a session that was established by issuing a "Call" command. ============================= Additional Information ============================= Much of the information above assumes knowledge of NetBIOS. For more information, consult: C Programmers Guide to NetBIOS, IPX, and SPX by W. David Schwaderer, SAMS Publishing, a division of Prentice Hall Computer Publishing, 11711 North College, Carmel, Indiana 46032, USA ============================= Release Notes ============================= Version 1.3 Added "Visible" property, which was inadvertently missing in earlier versions. Added SendTimeout and RecTimeout properties, to allow setting of timeouts for sessions. Earlier versions used 20 half-seconds as the timeout for both sends and receives. Increased the datagram buffer size from 256 to 512 bytes. Version 1.4 Added the SessionInfo event. Version 1.5 Fixed a problem with the NetCom control putting a NULL (0) in the last byte of the net name. It now puts spaces in all positions after the end of the name. This makes it more compatible with other NetBios programs. ================================================================ Northeast Data Corp. 2117 Buffalo Rd., Suite 290 Rochester, NY 14624 716-247-5934 (phone & FAX) ================================================================ April 3, 1994